VpUserInfo.nsf contains user information that the Sametime client stores on the server. This data consists of the contact list of each user who logged in to the server, the privacy list of these users and other types of user specific information. In a clustered Sametime environment, the VpUserInfo.nsf is replicated between the cluster nodes by means of Domino replication. The result is that the VpUserInfo.nsf is in sync and is identical across all servers in the cluster.
Each entry in the nsf is identified by a unique user ID which is called Sametime user ID. The format of this ID is different between the native Domino Directory and the Domino LDAP Directory.
To allow users to continue using their existing Sametime contact lists after the environment is moved to a Domino LDAP Directory, the VpUserInfo.nsf database must be migrated to convert the formats of the user and group IDs in the nsf to the LDAP format.
Steps to consider and implement before the migration
General recommendations
1. To avoid many known issues during the migration, it is highly recommended that you upgrade all Sametime clients to at least 8.5.2 before the migration.
2. It is recommended not to change the Directory related configuration of existing servers because the process is quite complicated. Either new Sametime community servers machines should be installed or, in the case that the same machines will continue to be used, Sametime should be removed on those machines and installed again, this time with an LDAP configuration. This document focuses on a migration that uses new machines for the migrated environment. The differences between such a migration and using the same server machines as before the migration are minimal.
he following Community Server configuration files should be backed up from each of the Community Servers in the deployment before migrating the environment:
The user's Sametime contact list is stored both locally in the Sametime Connect and or Notes clients and in the user's entry in VpUserInfo.nsf on the Community server. During the login to Sametime, the client retrieves the server's copy of the user's contact lists and compares it to the local one. If there is a difference between the two copies, it needs to decide which copy should be used as the user's contact list. The following client preference defines what to do when the local contact list is out of sync with the contact list on the server:
When the client's preference is to replace the local copy with the server copy, the client stores the server copy of the contact list locally. At logout, the client stores the local copy of the contact list on the server.
Before a user logs in for the first time to the migrated server, the local copy of the contact list still contains the old native Domino format of user and group IDs. Meanwhile, the server's copy of the contact list stored in the migrated VpUserInfo.nsf database uses the migrated Domino LDAP format. You
The symptoms of wrong contact list copy being used by the client are that awareness is successfully shown for any searched user and group and for any new contact which is added to the contact lists while all the contacts which were available prior to the migration are shown offline in the contact list.
Using the “Ask me what to do” option isn't good enough, because there will always be users who will choose the wrong option .
Luckily there are ways to make sure that this option will be automatically set for all the clients above version 8.5.
This is done by using managed preferences. Please note that in Sametime clients embedded in Notes clients , the relevant version refers to the Sametime plugin inside the Notes client, not the Notes client version.
The managed preferences that need to be set so that the server's copy of the contact list will replace the local copy and the users will not be bothered by any pop-up windows related to contact list modification during the login are:
Please note that according to the instructions for setting up the managed preferences file, the xml file must contain the
tag. So if no additional preferences are added, the managed preferences xml file will look like this:
<ManagedSettings>
<settingGroup name="com.ibm.collaboration.realtime.imhub">
<setting name="showBuddyListConflictDialog" value="false" isLocked="true" overwriteUnlocked="true"/>
<setting name="buddyListConflictPref" value="replaceLocal" isLocked="true" overwriteUnlocked="true"/>
<setting name="showExternalModificationDialog" value="false" isLocked="true"/>
</settingGroup>
</ManagedSettings>
For clients older than 8.5 centralized managed preferences can't be used for solving this issue, so instead the following settings should be set locally in the plugin_customization.ini file on the client machines:
com.ibm.collaboration.realtime.imhub/showBuddyListConflictDialog=false
com.ibm.collaboration.realtime.imhub/buddyListConflictPref=replaceLocal
com.ibm.collaboration.realtime.imhub/showExternalModificationDialog=false
See Configuring Sametime Connect client preferences in the plugin_customization.ini file
Steps required for Inbox awareness to work
If the Notes client inbox awareness feature is used, the Use canonical names for status lookup setting should be enabled in the Notes clients:
Clients which do not enable this option will not show inbox awareness with Domino LDAP Directory unless additional changes are performed on the Directory. Inbox awareness will not work unless this setting is enabled, the names are sent to the Sametime Community Server and from there to the Directory in Domino hierarchical format. Names in that format can not be found in Domino LDAP Directory by default. In addition, enabling this setting improves the performance of the Sametime searches. This is because inbox awareness uses the Sametime search functionality and using canonical names creates LDAP search requests which can be responded much faster by the LDAP.
As with the setting which defines which copy of the contact list is used by the client, here there is also a managed preference that makes sure that the correct value will be automatically set for all the clients above version 8.0.2 20090826. The managed preference is:
<settingGroup name="com.ibm.collaboration.realtime.community">
<setting name="useCanonicalNamesOverride" value="1"/>
</settingGroup>
Clients older than 8.0.2 20090826 do not use this managed preference. This setting must be enabled manually from the client's UI.
Issues with Community Server host names
As mentioned above, a user's Sametime contact list is stored both locally in the Sametime Connect or Notes client and in the user's entry in VpUserInfo.nsf on the Community server. Among others the user's contact list contains the definition of the different communities the user logs into and the actual contact lists. Each community is defined by a community name that is configured by ST_COMMUNITY_ID flag under [Config] section in the sametime.ini. When the flag is not set, the default value is the server host name (a specific sametime node that user logs into ) All the contacts in the contact list are associated with a specific community ID. For example if a user logs into community sametime.ibm.com and adds contact A, that contact will be associated with the community sametime.ibm.com. If the users logs into sametime2.ibm.com and adds contact B, that contact will be associated with community sametime2.ibm.com.
In case the host name used to log in to the migrated environment is different than the host name used for logging into the original production environment, the contacts already available in the contact lists will not properly display once a user logs with the new hostname. This is because once a login to the new hostname occurs, a new community definition is added to the contact list and the already available contacts are not associated with this community. The symptoms can be an empty contact list or duplicate entries in the contact list.
Please note that this issue is relevant when using a new server hostname for the migrated server in both production and test environments.
There are several ways to solve these issues:
A. On the new server, set ST_COMMUNITY_ID flag under [Config] section in sametime.ini to the value of this flag from the old server. This will associate user login to original community. In case that the flag wasn't used on the old environment, it is possible to set on the new servers, the value of the hostname that was previously used to login to the old environment.
This option can be used only if the ST_COMMUNITY_ID was in use in old environment, or in case that all clients used the same hostname value to login to Sametime server.
See sample:
When the ST_COMMUNITY_ID is used with the name of a community, the "Server community name" will be predefined and read only for the end user.
Community name could be displayed on the Sametime Community Preference UI. For example:
When can this option not be used ?
- In cases when the old environment did not used ST_COMMUNITY_ID and was split into several connection host.
- In case when the old environment was configured with several ST_COMMUNITY_ID on different Sametime Community servers.
B. Use a server hostname identical to the old one - This is usually the best solution for the production cutover to the new migrated environment.However, this solution is usually not possible since the new server should be tested before going live. Instead of actually using the same hostname, a DNS alias can be added when going live from the old host name to the new one and so the clients would be still connecting to the old hostname.
While the solution with DNS alias can work for the production cutover, it can't be used for testing the migrated server before the actual cutover, since the regular users must still use the original server. To allow such testing, the users who test the migrated server can temporary change the hosts file on their client machines so during their tests the old hostname will point to the IP of the migrated server that is to be tested.
The hosts file can be easily modified on Windows client machines according to these instructions:
XP - http://kb.simplywebhosting.com/idx/0/045/article/
Win7 - http://helpdeskgeek.com/windows-7/windows-7-hosts-file/
On Linux the file is /etc/hosts.
C. Run the REPLACE_HOST name change task on the migrated VpUserInfo.nsf and change the old hostname to the new one. This should be done before the migrated VpUserInfo.nsf is used. Because this is a new name change task, name change fix AAZI-9CBDH4 or a later fix containing this task must be used. More information about this fix can be found at https://www-304.ibm.com/support/docview.wss?uid=swg21652354.
After applying this step, it is strongly recommend to set ST_COMMUNITY_ID value on migrated servers. This is in order to mark all Sametime servers in the environment as belonging to one community.
Instructions for running the REPLACE_HOST name change task:
1) Create a CSV file with the values below adding REPLACE_HOST then the old and new values.
example:
REPLACE_HOST
"OldCommunityHost.com","Newcommunityhost.com"
This task can also merge multiple community names into one using the below syntax.
See csv file sample content, to merge 4 different community IDs into the new one:
REPLACE_HOST
"OldCommunityHost1.com","Newcommunityhost.com"
"OldCommunityHost2.com","Newcommunityhost.com"
"OldCommunityHost3.com","Newcommunityhost.com"
"OldCommunityHost4.com","Newcommunityhost.com"
2) Create a name change task and Run the STNamechange as you would for any name change operation. See Changing names as needed.
All these different solutions achieve the desired result. The user logs in to the migrated server and the hostname stored in the community definition in the user's entry of the nsf matches the hostname required to login, so the contact list is displayed correctly.
Updating the Sametime home server configuration in the Directory
If the hostname of the migrated servers are different than the hostnames of the original servers and the user entries in the Directory contain the old names of the servers in the “Instant messaging server” field, those entries in the Directory must be updated. Otherwise the users will not be able to login to Sametime. The same is true for updated cluster names if user entries contain names of Sametime clusters that were changed.
Login to Notes basic clients
When a Notes basic client is used to log in to Sametime, the user ID that is used by default on the login screen is the Notes hierarchical representation of the user's DN. For example:
Julia Herlihy/Sales/East/Acme/US
Such an ID works when a native Domino Directory is used by Sametime. However, this authentication doesn't work with Domino LDAP. The ID must be changed to another unique ID like a mail or Notes canonical DN. For instance, the following canonical name can be used:
CN=Julia Herlihy/OU=Sales/OU=East/O=Acme/C=US
Contacts display names
User display names are also stored in the contact lists in VpUserInfo.nsf. These names are not updated during the migration of the database. When a user logs in to a newly migrated server, the display names of the contacts remain identical to how they appeared before the migration. They appear in the Notes hierarchical format. For example:
Julia Herlihy/Sales/East/Acme/US
When a new name is added to a contact list, it will follow the LDAP format:
Julia Herlihy
Existing display names in the old Notes hierarchical format will change whenever the client searches for a user in the Directory (through the Sametime quick find bar or inbox awareness). When the search is performed through a Community Server that accesses the Directory with the LDAP protocol, the returned display name is different than the one that was returned from native Domino Directory. The client recognizes that the display name is different from the stored one and updates the contact list with the new display name.
Migration
Database migration guidelines
The preceding information implies that to migrate the environment from a native Domino Directory to a Domino LDAP, the content of the VpUserInfo.nsf database must be migrated, so the format of the Sametime user and group IDs will be updated to the new format. This process is done by using the name conversion utility.
Name conversion utility best practices:
- Backup existing VpUserInfo.nsf files. In cluster topology, the operation should be done on a single VpUserInfo.nsf per cluster. In a non-clustered topology, the operation should be done on each Sametime server.
- Remove all CSV tasks from stnamechange.nsf before you run the NameChange utility. This ensures that only a single task for the LDAP migration is performed.
- Check the VpUserInfo.nsf- > NameChange view for any record that is marked as completed. When the NameChange utility detects that a task with a specific ID was performed, the task will not be performed again. Therefore, for the namechange to run properly, remove the completed tasks.
- The latest available NameChange hotfix should be used for the conversion. For the time this document is released, such hotfix is AAZI-9CBDH4. All fixes can be obtained from Fix Central
- The conversion operation whether on a single or multiple VpUserInfo.nsf file should be done on a single test server.
- In cluster topology, the operation should be done on a single VpUserInfo.nsf per cluster.
- In a non-clustered topology, the operation should be done on VpUserInfo.nsf from each Sametime Community Server.
- Namechange LDAP task must run only once on VpUserInfo.nsf that has native Domino ID format names. Running multiple LDAP tasks on the same VpUserInfo.nsf may generate inconsistent results that may cause awareness issues. In case that the VpUserInfo.nsf migration failed and needs to be repeated, please use the original nsf and not the already migrated nsf.
- Once name conversion is completed, a report is generated to notify you of NameChange errors and entries of specific users which couldn't be converted. The number of such users should be minimal. These users will need to manually recreate their contact lists. The report is available under the trace folder in a file with the following name format: name_change_summary_report__
- Run commands on the new migrated VpUserInfo.nsf for consistency and validation purposes:
1. Shut down the Sametime server by executing the "quit" command.
2. Open a command prompt and navigate to the Domino program directory (i.e. \lotus\domino).
3. Run the following maintenance commands:
C:\lotus\domino\>ncompact VpUserInfo.nsf -C -D -i
C:\lotus\domino\>nupdall VpUserInfo.nsf -c
C:\lotus\domino\>nfixup VpUserInfo.nsf -f
- After running the name conversion utility, backup the migrated VpUserInfo.nsf files before using the files
- Refer to the Administering Sametime Standard 8.5.2 Interim Feature Release 1 documentation for complete instructions on using the name conversion utility
Disabling adminP
The name change adminP integration is relevant for native Domino Directory only. It must be disabled on a Community Server that uses an LDAP Directory. Disabling adminP is done by removing the following line from notes.ini:
EXTMGR_ADDINS=StUpdateAdminP.dll
Adding a home Server Directory attribute name to the Community Server configuration
In a clustered or distributed Sametime environment that uses an LDAP Directory, the LDAP attribute containing the name of the users' home server must be specified in the Sametime Community Server LDAP configuration. For Domino LDAP the value to be set is SametimeServer. It is to be set into the Name of the Home Server Attribute field of the LDAP document in StConfig.nsf. Without this setting, users will not be able to log in to Sametime.
Updating the Sametime clusters names
Domino LDAP always returns the server or cluster name configured in the “Instant messaging server” field in the user's entry in the Directory in notes canonical format. This means that it will always start with CN=. In case that Sametime clusters are used and their names don't start with CN= when using native Domino Directory, the Sametime cluster names will need to be changed and the CN= prefix must be added. Otherwise users will not be able to log in to Sametime. This change is done in the cluster documents in StConfig.nsf on all the Community Servers. The only field to be changed is the “Cluster Name” field.
Emptying the local address books
The migrated Community Server now uses an LDAP Directory and not the local names.nsf. In case that the same machine that was previously used with native Domino Directory was migrated to use an LDAP Directory, for example by uninstalling Sametime and installing it again this time with LDAP configuration, the local names.nsf and other address books might still contain the organization's users and groups as previously. If that's the case, names.nsf should be emptied and any other address book pointed from DA.nsf should be removed from DA.nsf. DA.nsf should only point to the LDAP currently used by the Community Server.
Leaving the local address books non-empty on the Community Server might cause Single Sign-On issues and slower Domino server initialization and shutdown, but the basic Sametime functionality should not be affected.
Setting the converted VpUserInfo.nsf files on the migrated servers
At this point you should have new Community Servers installed with the LDAP Directory configuration. All the steps discussed in the previous sections must be implemented and the environment specific settings must be copied from the originally backed up configuration files to the new servers. Now the migrated VpUserInfo.nsf files should be placed on the new servers.
Sametime clustered topology
1. Turn off replication on all production servers from the Domino console:
Tell replica quit
Tell clrepl quit
2. Stop all Domino servers in the Community.
3. Rename the existing VPUserinfo.nsf to be VPUserinfoOld.nsf and move it to a backup folder.
4. Copy the new migrated Vpuserinfo.nsf to the default location of Vpuserinfo.nsf → under the Domino/data folder.
5. Start the server. Test and verify that it is working.
6. Once verification is complete, copy new migrated Vpuserinfo.nsf to all remaining servers in the cluster.
7. Start remaining servers one by one. Test and verify that everything is working.
8. Turn on replicator on all servers.
Sametime non-clustered topology
In distributed topology, Vpuserinfo.nsf is not replicated between servers, each server should have its own copy of migrated VpUserInfo.nsf.
The following steps should be done on each of the servers in the Community:
1. Stop all Domino servers in the Community
2. Rename the existing VPUserinfo.nsf to be VPUserinfoOld.nsf and move it to a backup folder.
3. Copy the new migrated Vpuserinfo.nsf to the default location of Vpuserinfo.nsf → under Domino/data folder.
4. Start the server. Test and verify that it is working.
Testing
Testing the migration is mandatory to make sure that the production migration is successful and completed on the first attempt without causing problems to end users. Note that all the steps discussed previously are relevant for both migrated test servers and migrated production servers. Specifically when testing, note the “Community Server host names” section. That particular point is missed in many cases during the tests which causes the functionality to break.
Please note that during the testing the only users who are going to be seen as online are the users who login to the migrated test servers. Users who are logged in to the original production servers will not be seen as online to the users logged in to the migrated servers and the other way around, even if the migrated test servers were added to the production community. The reason is the different format of the user IDs used by the migrated servers, which now use an LDAP format and non-migrated servers that use the Notes hierarchical name format.
Recomended functional testing
It is recommended that a number of users will log in to the test servers with all the client types used in the organization and perform at least the following functionality tests:
• Login
• Users awareness
• Public groups content and awareness
• Contact list availability and correctness. Specifically note that all the entries in the contact list are in place and there are no duplicate entries.
• Chat
• Searching users and public groups in the Directory
• Inbox awareness (for Notes embedded clients)
• Business cards correctness
• Policies functionality
Load testing
It is recommended to perform load testing on the Domino LDAP servers to validate that they can handle the load expected to be generated by the Sametime Community Servers.
Domino LDAP configuration and performance optimization
Accessing Domino LDAP as anonymous LDAP client
By default Domino LDAP does not allow anonymous LDAP clients to see the SametimeServer attribute which is required in a distributed or clustered Sametime environment to specify the user's home server. Either an authenticated LDAP connection must be used by the Sametime Community Servers or the Domino LDAP configuration should be changed in names.nsf to allow the SametimeServer attribute to be searchable by anonymous LDAP clients. To use an authenticated LDAP connection for Sametime, just specify the credentials in the appropriate fields in Sametime LDAP settings.
See how to set the Domino LDAP settings in names.nsf to enable anonymous access to the SametimeServer attribute from anonymous LDAP clients
Performance optimization
To allow the Domino LDAP severs handle the load coming through the LDAP protocol from Sametime Community Servers, at least the following steps should be followed on the Domino LDAP servers:
• Indexing
Every address book available in the Domino LDAP must be full text indexed.(FTI)
• Cache
Domino LDAP cache is disabled by default. It must be manually enabled in notes.ini on the Domino LDAPs:
LDAP_QRCACHE_SIZE=268435456
NLCACHE_SIZE=268435456
For Domino LDAPs with lots of RAM which are dedicated for Sametime, the size can be set higher:
LDAP_QRCACHE_SIZE=536870912
NLCACHE_SIZE=536870912
Domino LDAP server must be restarted for the changed to take affect.
Note that only hits are added to the Domino LDAP cache. Searches that don't find a match in the cache slow the LDAP greatly, meaning that the number of searches unmatched in the Directory should be as minimal as possible. The ways to achieve this are discussed in the “Optimizing Sametime searches performance” section.
• Number of worker threads
Domino LDAP uses 40 worker threads by default for handling LDAP requests. The number should be raised to 80 in notes.ini:
LDAPMaxWorkerThreads=80
For Domino LDAPs with lots of RAM which are dedicated for Sametime, the size can be set higher:
LDAPMaxWorkerThreads=120
Domino LDAP server must be restarted for the changed to take affect.
• DA.nsf considerations
Unnecessary secondary address books pointed by DA.nsf on the Domino LDAP servers must be removed from DA.nsf or be disabled for LDAP searches.
Optimizing Sametime search performance
Optimizing Name Lookup: LDAP Directory servers
Optimizing Name Lookup: Sametime server
References
IBM Sametime 8.5.2 IFR1 Technical Documentation
Domino and Notes Technical Documentation:
Trademarks
Domino, IBM, Notes, Sametime and WebSphere are trademarks or registered trademarks of IBM Corporation in the United States, other countries, or both.
Other company, product, and service names may be trademarks or service marks of others.